troika-three-utils

What is troika-three-utils?

The troika-three-utils package provides a collection of utility functions and classes to simplify common tasks when working with Three.js, a popular 3D library for JavaScript. These utilities help with tasks such as geometry manipulation, shader management, and scene graph operations.

What are troika-three-utils's main functionalities?

Geometry Utilities

This feature allows you to merge multiple geometries into a single geometry. This can be useful for optimizing performance by reducing the number of draw calls.

const { mergeBufferGeometries } = require('troika-three-utils');
const geometry1 = new THREE.BoxGeometry(1, 1, 1);
const geometry2 = new THREE.SphereGeometry(0.5, 32, 32);
const mergedGeometry = mergeBufferGeometries([geometry1, geometry2]);

Shader Utilities

This feature allows you to create a derived material from an existing material, adding custom shaders and uniforms. This is useful for creating complex visual effects without having to write a new material from scratch.

const { createDerivedMaterial } = require('troika-three-utils');
const baseMaterial = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
const derivedMaterial = createDerivedMaterial(baseMaterial, {
  uniforms: {
    time: { value: 0 }
  },
  vertexShader: 'varying float vTime; void main() { vTime = time; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }',
  fragmentShader: 'varying float vTime; void main() { gl_FragColor = vec4(vTime, 0.0, 0.0, 1.0); }'
});

Scene Graph Utilities

This feature provides a utility to traverse the scene graph, applying a callback function to each object. This can be useful for operations like searching for specific objects or applying transformations.

const { traverseScene } = require('troika-three-utils');
const scene = new THREE.Scene();
const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial());
scene.add(mesh);
traverseScene(scene, (object) => {
  console.log(object);
});

0

README

Troika Three.js Utilities

This package provides various utilities for working with Three.js, particularly having to do with shaders. It is used by Troika 3D, but has no dependencies itself other than Three.js, so it can be used outside the Troika framework.

Installation

Get it from NPM:

npm install troika-three-utils

You will also need to install a compatible version of Three.js, which is declared with a wide version range in peerDependencies rather than a direct dependency on a specific version, to give you flexibility in choosing a specific version for your application.

npm install three

You can look in the package.json under "peerDependencies" for a range of Three.js versions that has been verified to work with this and all other Troika packages. Other versions that have not been specifically tested may also work depending on the features you use, they just haven't been explicitly tested.

Provided Utilities

Several utilities are provided; for a full list follow the imports in index.js to their source files, where each is documented in JSDoc comments.

Some of the most useful ones are:

createDerivedMaterial()

This utility allows you to easily extend existing Three.js materials with your own custom shader code. This is an incredibly powerful tool, and is the secret behind most of Troika's shader-driven tools like troika-three-text, three-instanced-uniforms-mesh, and BezierMesh.

See the createDerivedMaterial documentation page and its source code with JSDoc for details.

BezierMesh

This creates a cylindrical mesh and bends it along a 3D cubic bezier path between two points, in a custom derived vertex shader. This is useful for visually connecting objects in 3D space with a line that has thickness to it.

See the BezierMesh documentation page and its source code with JSDoc for details.

InstancedUniformsMesh

NOTE: InstancedUniformsMesh has been moved to its own three-instanced-uniforms-mesh package.

Changelog

0.40.0 (2021-02-28)

Bug Fixes

• troika-three-text: fix boundingBox, boundingSphere, and raycasting with curveRadius (7cc7c82), closes #103

Features

• troika-3d: add initThreeObject lifecycle method to Object3DFacade (230a87d)
• troika-3d: remove need for manually defining material.instanceUniforms (a234f8c)